=begin pod

=TITLE class Cool

=SUBTITLE Object that can be treated as both a string and number

    class Cool is Any { }

C<Cool>, also known as the B<C>onvenient B<OO> B<L>oop, is a base class
employed by a number of built-in classes that can be meaningfully coerced
to a string and a number. For example, an L<Array> can be used in mathematical
operations, where its numerical representation is the number of elements it
contains. At the same time, it can be concatenated to a string, where its
stringy representation is all of its elements L<joined|/routine/join> by
a space. Because L<Array> is L<Cool>, the appropriate coercion happens
automatically.

Methods in C<Cool> coerce the invocant to a more
specific type, and then call the same method on that type. For example both
L<Int> and L<Str> inherit from C<Cool>, and calling method C<substr> on an
C<Int> converts the integer to C<Str> first.

    123.substr(1, 1);   # '2', same as 123.Str.substr(1, 1)

The following built-in types inherit from C<Cool>:
L<Array> L<Bool> L<Complex> L<Cool>
L<Duration> L<Map> L<FatRat> L<Hash> L<Instant>
L<Int> L<List> L<Match> L<Nil> L<Num>
L<Range> L<Seq> L<Stash> L<Str>

The following table summarizes the methods that C<Cool> provides, and
what type they coerce to:

=begin table

    method          coercion type

    abs             Numeric
    conj            Numeric
    sqrt            Numeric
    sign            Real
    rand            Numeric
    sin             Numeric
    asin            Numeric
    cos             Numeric
    acos            Numeric
    tan             Numeric
    tanh            Numeric
    atan            Numeric
    atan2           Numeric
    atanh           Numeric
    sec             Numeric
    asec            Numeric
    cosec           Numeric
    acosec          Numeric
    cotan           Numeric
    cotanh          Numeric
    acotan          Numeric
    sinh            Numeric
    asinh           Numeric
    cosh            Numeric
    acosh           Numeric
    sech            Numeric
    asech           Numeric
    cosech          Numeric
    acosech         Numeric
    acotanh         Numeric
    cis             Numeric
    log             Numeric
    exp             Numeric
    roots           Numeric
    log10           Numeric
    unpolar         Numeric
    round           Numeric
    floor           Numeric
    ceiling         Numeric
    truncate        Numeric
    chr             Int
    ord             Str
    chars           Str
    fmt             Str
    uniname         Str
    uninames        Seq
    unival          Str
    univals         Str
    uniprop         Str
    uniprop-int     Str
    uniprop-str     Str
    uniprop-bool    Str
    unimatch        Str
    uc              Str
    lc              Str
    fc              Str
    tc              Str
    tclc            Str
    flip            Str
    trans           Str
    contains        Str
    index           Str
    rindex          Str
    ords            Str
    split           Str
    match           Str
    comb            Str
    subst           Str
    sprintf         Str
    printf          Str
    samecase        Str
    trim            Str
    trim-leading    Str
    trim-trailing   Str
    EVAL            Str
    chomp           Str
    chop            Str
    codes           Str

=end table

=head1 Methods

=head2 routine abs

Defined as:

    sub abs(Numeric() $x)
    method abs()

Coerces the invocant (or in the sub form, the argument) to
L<Numeric|/type/Numeric> and returns the absolute value (that is, a
non-negative number).

    say (-2).abs;       # OUTPUT: «2␤»
    say abs "6+8i";     # OUTPUT: «10␤»

=head2 method conj

Defined as:

    method conj()

Coerces the invocant to L<Numeric|/type/Numeric> and returns the
L<complex|/type/Complex> conjugate (that is, the number with the sign of the
imaginary part negated).

    say (1+2i).conj;        # OUTPUT: «1-2i␤»

=head2 routine sqrt

Defined as:

    sub sqrt(Numeric(Cool) $x)
    method sqrt()

Coerces the invocant to L<Numeric|/type/Numeric> (or in the sub form, the
argument) and returns the square root,
that is, a non-negative number that, when multiplied with itself, produces the
original number.

    say 4.sqrt;             # OUTPUT: «2␤»
    say sqrt(2);            # OUTPUT: «1.4142135623731␤»

=head2 method sign

Defined as:

    method sign()

Coerces the invocant to L<Numeric|/type/Real> and returns its sign, that
is, 0 if the number is 0, 1 for positive and -1 for negative values.

    say 6.sign;             # OUTPUT: «1␤»
    say (-6).sign;          # OUTPUT: «-1␤»
    say "0".sign;           # OUTPUT: «0␤»

=head2 method rand

Defined as:

    method rand()

Coerces the invocant to L<Num|/type/Num> and returns a pseudo-random value
between zero and the number.

    say 1e5.rand;           # OUTPUT: «33128.495184283␤»

=head2 routine sin

Defined as:

    sub sin(Numeric(Cool))
    method sin()

Coerces the invocant (or in the sub form, the argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<sine|https://en.wikipedia.org/wiki/Sine>.

    say sin(0);             # OUTPUT: «0␤»
    say sin(pi/4);          # OUTPUT: «0.707106781186547␤»
    say sin(pi/2);          # OUTPUT: «1␤»

Note that Perl 6 is no computer algebra system, so C<sin(pi)> typically does
not produce an exact 0, but rather a very small L<floating-point
number|/type/Num>.

=head2 routine asin

Defined as:

    sub asin(Numeric(Cool))
    method asin()

Coerces the invocant (or in the sub form, the argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-sine|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say 0.1.asin;               # OUTPUT: «0.10016742116156␤»
    say asin(0.1);              # OUTPUT: «0.10016742116156␤»

=head2 routine cos

Defined as:

    sub cos(Numeric(Cool))
    method cos()

Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<cosine|https://en.wikipedia.org/wiki/Cosine>.

    say 0.cos;                  # OUTPUT: «1␤»
    say pi.cos;                 # OUTPUT: «-1␤»
    say cos(pi/2);              # OUTPUT: «6.12323399573677e-17␤»

=head2 routine acos

Defined as:

    sub acos(Numeric(Cool))
    method acos()

Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-cosine|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say 1.acos;                 # OUTPUT: «0␤»
    say acos(-1);               # OUTPUT: «3.14159265358979␤»

=head2 routine tan

Defined as:

    sub tan(Numeric(Cool))
    method tan()

Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<tangent|https://en.wikipedia.org/wiki/Tangent>.

    say tan(3);                 # OUTPUT: «-0.142546543074278␤»
    say 3.tan;                  # OUTPUT: «-0.142546543074278␤»

=head2 routine atan

Defined as:

    sub atan(Numeric(Cool))
    method atan()

Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-tangent|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say atan(3);                # OUTPUT: «1.24904577239825␤»
    say 3.atan;                 # OUTPUT: «1.24904577239825␤»

=head2 routine atan2

Defined as:

    sub atan2(Numeric() $x, Numeric() $y = 1e0)
    method atan2($y = 1e0)

Coerces the arguments (including the invocant in the method form) to L<Numeric|/type/Numeric>,
and returns their two-argument
L<arc-tangent|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say atan2(3);               # OUTPUT: «1.24904577239825␤»
    say 3.atan2;                # OUTPUT: «1.24904577239825␤»

=head2 method sec

Defined as:

    sub sec(Numeric(Cool))
    method sec()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<secant|https://en.wikipedia.org/wiki/Trigonometric_functions#Reciprocal_functions>,
that is, the reciprocal of its cosine.

    say 45.sec;                 # OUTPUT: «1.90359440740442␤»
    say sec(45);                # OUTPUT: «1.90359440740442␤»

=head2 routine asec

Defined as:

    sub asec(Numeric(Cool))
    method asec()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-secant|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say 1.asec;                 # OUTPUT: «0␤»
    say sqrt(2).asec;           # OUTPUT: «0.785398163397448␤»

=head2 routine cosec

Defined as:

    sub cosec(Numeric(Cool))
    method cosec()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<cosecant|https://en.wikipedia.org/wiki/Trigonometric_functions#Reciprocal_functions>,
that is, the reciprocal of its sine.

    say 0.45.cosec;             # OUTPUT: «2.29903273150897␤»
    say cosec(0.45);            # OUTPUT: «2.29903273150897␤»

=head2 routine acosec

Defined as:

    sub acosec(Numeric(Cool))
    method acosec()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-cosecant|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say 45.acosec;              # OUTPUT: «0.0222240516182672␤»
    say acosec(45)              # OUTPUT: «0.0222240516182672␤»

=head2 routine cotan

Defined as:

    sub cotan(Numeric(Cool))
    method cotan()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<cotangent|https://en.wikipedia.org/wiki/Trigonometric_functions#Reciprocal_functions>,
that is, the reciprocal of its tangent.

    say 45.cotan;               # OUTPUT: «0.617369623783555␤»
    say cotan(45);              # OUTPUT: «0.617369623783555␤»

=head2 routine acotan

Defined as:

    sub acotan(Numeric(Cool))
    method acotan()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-cotangent|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say 45.acotan;              # OUTPUT: «0.0222185653267191␤»
    say acotan(45)              # OUTPUT: «0.0222185653267191␤»

=head2 routine sinh

Defined as:

    sub sinh(Numeric(Cool))
    method sinh()

Coerces the invocant (or in method form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Sine hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say 1.sinh;                 # OUTPUT: «1.1752011936438␤»
    say sinh(1);                # OUTPUT: «1.1752011936438␤»

=head2 routine asinh

Defined as:

    sub asinh(Numeric(Cool))
    method asinh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse Sine hyperbolicus|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say 1.asinh;                # OUTPUT: «0.881373587019543␤»
    say asinh(1);               # OUTPUT: «0.881373587019543␤»

=head2 routine cosh

Defined as:

    sub cosh(Numeric(Cool))
    method cosh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Cosine hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say cosh(0.5);              # OUTPUT: «1.12762596520638␤»

=head2 routine acosh

Defined as:

    sub acosh(Numeric(Cool))
    method acosh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse Cosine hyperbolicus|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say acosh(45);              # OUTPUT: «4.4996861906715␤»

=head2 routine tanh

Defined as:

    sub tanh(Numeric(Cool))
    method tanh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, interprets it as
radians and returns its L<Tangent hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say tanh(0.5);              # OUTPUT: «0.46211715726001␤»
    say tanh(atanh(0.5));       # OUTPUT: «0.5␤»

=head2 routine atanh

Defined as:

    sub atanh(Numeric(Cool))
    method atanh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse tangent hyperbolicus|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say atanh(0.5);             # OUTPUT: «0.549306144334055␤»

=head2 routine sech

Defined as:

    sub sech(Numeric(Cool))
    method sech()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Secant hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say 0.sech;                 # OUTPUT: «1␤»

=head2 routine asech

Defined as:

    sub asech(Numeric(Cool))
    method asech()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse hyperbolic secant|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say 0.8.asech;              # OUTPUT: «0.693147180559945␤»

=head2 routine cosech

Defined as:

    sub cosech(Numeric(Cool))
    method cosech()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Hyperbolic cosecant|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say cosech(pi/2);           # OUTPUT: «0.434537208094696␤»

=head2 routine acosech

Defined as:

    sub acosech(Numeric(Cool))
    method acosech()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse hyperbolic cosecant|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say acosech(4.5);           # OUTPUT: «0.220432720979802␤»

=head2 routine cotanh

Defined as:

    sub cotanh(Numeric(Cool))
    method cotanh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Hyperbolic cotangent|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say cotanh(pi);             # OUTPUT: «1.00374187319732␤»

=head2 routine acotanh

Defined as:

    sub acotanh(Numeric(Cool))
    method acotanh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse hyperbolic cotangent|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say acotanh(2.5);           # OUTPUT: «0.423648930193602␤»

=head2 routine cis

Defined as:

    sub cis(Numeric(Cool))
    method cis()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns
L<cos(argument) + i*sin(argument)|https://en.wikipedia.org/wiki/Cis_%28mathematics%29>.

    say cis(pi/4);              # OUTPUT: «0.707106781186548+0.707106781186547i␤»

=head2 routine log

Defined as:

    multi sub log(Numeric(Cool) $number, Numeric(Cool) $base?)
    multi method log(Cool:D: Cool:D $base?)

Coerces the arguments (including the invocant in the method form) to
L<Numeric|/type/Numeric>, and returns its
L<Logarithm|https://en.wikipedia.org/wiki/Logarithm> to base C<$base>, or to
base C<e> (Euler's Number) if no base was supplied
(L<Natural logarithm|https://en.wikipedia.org/wiki/Natural_logarithm>).
Returns C<NaN> if C<$base> is negative. Throws an exception if C<$base> is C<1>.

    say (e*e).log;              # OUTPUT: «2␤»

=head2 routine log10

Defined as:

    multi sub log10(Cool(Numeric))
    multi method log10()

Coerces the invocant (or in the sub form, the invocant) to
L<Numeric|/type/Numeric>, and returns its
L<Logarithm|https://en.wikipedia.org/wiki/Logarithm> to base 10, that is, a
number that approximately produces the original number when raised to the power
of 10. Returns C<NaN> for negative arguments and C<-Inf> for C<0>.

    say log10(1001);            # OUTPUT: «3.00043407747932␤»

=head2 method exp

Defined as:

    multi sub exp(Cool:D $pow, Cool:D $base?)
    multi method exp(Cool:D: Cool:D $base?)

Coerces the arguments (including the invocant in the method from) to L<Numeric|/type/Numeric>, and returns C<$base>
raised to the power of the first number. If no C<$base> is supplied, C<e> (Euler's
Number) is used.

    say 0.exp;      # OUTPUT: «1␤»
    say 1.exp;      # OUTPUT: «2.71828182845905␤»
    say 10.exp;     # OUTPUT: «22026.4657948067␤»

=head2 method unpolar

Defined as:

    method unpolar(Numeric(Cool))

Coerces the arguments (including the invocant in the method form) to L<Numeric|/type/Numeric>, and returns
a complex number from the given polar coordinates. The invocant (or the first argument in sub form) is the magnitude while
the argument (i.e. the second argument in sub form) is the angle. The angle is assumed to be in radians.

    say sqrt(2).unpolar(pi/4);      # OUTPUT: «1+1i␤»

=head2 routine round

Defined as:

    multi sub round(Numeric(Cool))
    multi method round(Cool:D: $unit = 1)

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and rounds it to the unit of
C<$unit>. If C<$unit> is 1, rounds to the nearest integer.

    say 1.7.round;          # OUTPUT: «2␤»
    say 1.07.round(0.1);    # OUTPUT: «1.1␤»
    say 21.round(10);       # OUTPUT: «20␤»

Always rounds B<up> if the number is at mid-point:

    say (−.5 ).round;       # OUTPUT: «0␤»
    say ( .5 ).round;       # OUTPUT: «1␤»
    say (−.55).round(.1);   # OUTPUT: «-0.5␤»
    say ( .55).round(.1);   # OUTPUT: «0.6␤»

=head2 routine floor

Defined as:

    multi sub floor(Numeric(Cool))
    multi method floor

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and rounds it downwards to
the nearest integer.

    say "1.99".floor;       # OUTPUT: «1␤»
    say "-1.9".floor;       # OUTPUT: «-2␤»
    say 0.floor;            # OUTPUT: «0␤»

=head2 routine ceiling

Defined as:

    multi sub ceiling(Numeric(Cool))
    multi method ceiling

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and rounds it upwards to
the nearest integer.

    say "1".ceiling;        # OUTPUT: «1␤»
    say "-0.9".ceiling;     # OUTPUT: «0␤»
    say "42.1".ceiling;     # OUTPUT: «43␤»

=head2 routine truncate

Defined as:

    multi sub truncate(Numeric(Cool))
    multi method truncate()

Coerces the invocant (or in sub form, its argument) to
L<Numeric|/type/Numeric>, and rounds it towards zero.

    say 1.2.truncate;       # OUTPUT: «1␤»
    say truncate -1.2;      # OUTPUT: «-1␤»

=head2 routine ord

Defined as:

    sub ord(Str(Cool))
    method ord()

Coerces the invocant (or in sub form, its argument) to
L<Str|/type/Str>, and returns the L<Unicode code
point|https://en.wikipedia.org/wiki/Code_point> number of the first
code point.

    say 'a'.ord;            # OUTPUT: «97␤»

The inverse operation is L<chr|#method chr>.

Mnemonic: returns an ordinal number

=head2 routine chr

Defined as:

    sub chr(Int(Cool))
    method chr()

Coerces the invocant (or in sub form, its argument) to L<Int|/type/Int>, interprets it as a
L<Unicode code points|https://en.wikipedia.org/wiki/Code_point>,
and returns a L<string|/type/Str> made of that code point.

    say '65'.chr;       # OUTPUT: «A␤»

The inverse operation is L<ord|#method ord>.

Mnemonic: turns an integer into a I<char>acter.

=head2 routine chars

Defined as:

    sub chars(Str(Cool))
    method chars()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns the
number of characters in the string. Please note that on the JVM, you currently get
codepoints instead of graphemes.

    say 'møp'.chars;    # OUTPUT: «3␤»

=head2 routine codes

Defined as:

    sub codes(Str(Cool))
    method codes()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns the number of
L<Unicode code points|https://en.wikipedia.org/wiki/Code_point>.

    say 'møp'.codes;    # OUTPUT: «3␤»

The same result will be obtained with

    say +'møp'.ords;    # OUTPUT: «3␤»

L<ords> first obtains the actual codepoints, so there might be a difference in speed.

=head2 routine flip

Defined as:

    sub flip(Str(Cool))
    method flip()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns a reversed version.

    say 421.flip;       # OUTPUT: «124␤»

=head2 routine trim

Defined as:

    sub trim(Str(Cool))
    method trim()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns the string with both
leading and trailing whitespace stripped.

    my $stripped = '  abc '.trim;
    say "<$stripped>";          # OUTPUT: «<abc>␤»

=head2 routine trim-leading

Defined as:

    sub trim-leading(Str(Cool))
    method trim-leading()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns the string with
leading whitespace stripped.

    my $stripped = '  abc '.trim-leading;
    say "<$stripped>";          # OUTPUT: «<abc >␤»

=head2 routine trim-trailing

Defined as:

    sub trim-trailing(Str(Cool))
    method trim-trailing()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the string with trailing whitespace stripped.

    my $stripped = '  abc '.trim-trailing;
    say "<$stripped>";          # OUTPUT: «<  abc>␤»

=head2 routine lc

Defined as:

    sub lc(Str(Cool))
    method lc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it case-folded to lower
case.

    say "ABC".lc;       # OUTPUT: «abc␤»

=head2 routine uc

Defined as:

    sub uc(Str(Cool))
    method uc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it case-folded to upper
case (capital letters).

    say "Abc".uc;       # OUTPUT: «ABC␤»

=head2 routine fc

Defined as:

    sub fc(Str(Cool))
    method fc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the result a Unicode "case fold" operation suitable for doing caseless
string comparisons. (In general, the returned string is unlikely to be useful
for any purpose other than comparison.)

    say "groß".fc;       # OUTPUT: «gross␤»

=head2 routine tc

Defined as:

    sub tc(Str(Cool))
    method tc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it with the first letter
case-folded to title case (or where not available, upper case).

    say "abC".tc;       # OUTPUT: «AbC␤»

=head2 routine tclc

Defined as:

    sub tclc(Str(Cool))
    method tclc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it with the first letter
case-folded to title case (or where not available, upper case), and the rest
of the string case-folded to lower case.

    say 'abC'.tclc;     # OUTPUT: «Abc␤»

=head2 routine wordcase

Defined as:

    sub wordcase(Str(Cool) $input, :&filter = &tclc, Mu :$where = True)
    method wordcase(:&filter = &tclc, Mu :$where = True)

Coerces the invocant (or in sub form, the first argument) to L<Str|/type/Str>, and filters each word that
smart-matches against C<$where> through the C<&filter>. With the default
filter (first character to upper case, rest to lower) and matcher (which
accepts everything), this title-cases each word:

    say "perl 6 programming".wordcase;      # OUTPUT: «Perl 6 Programming␤»

With a matcher:

    say "have fun working on perl".wordcase(:where({ .chars > 3 }));
                                            # Have fun Working on Perl

With a customer filter too:

    say "have fun working on perl".wordcase(:filter(&uc), :where({ .chars > 3 }));
                                            # HAVE fun WORKING on PERL

=head2 routine samecase

Defined as:

    sub samecase(Cool $string, Cool $pattern)
    method samecase(Cool:D: Cool $pattern)

Coerces the invocant (or in sub form, the first argument) to L<Str|/type/Str>, and returns a
copy of C<$string> with case information for each individual character changed according to C<$pattern>.
(The pattern string can contain three types of characters, i.e. uppercase, lowercase and caseless.
For a given character in C<$pattern> its case information determines the case of the corresponding
character in the result.)
If C<$string> is longer than C<$pattern>, the case information from the last character of
C<$pattern> is applied to the remaining characters of C<$string>.

    say "perL 6".samecase("A__a__"); # OUTPUT: «Perl 6␤»
    say "pERL 6".samecase("Ab");     # OUTPUT: «Perl 6␤»

=head2 method uniprop

Defined as:

    multi sub uniprop(Str(Cool), |c)
    multi sub uniprop(Int:D $code, Stringy:D $propname)
    multi sub uniprop(Str, $code, Stringy:D $propname)
    multi method uniprop(|c)

Interprets the invocant as a L<Str|/type/Str>, and returns the
L<unicode property|http://userguide.icu-project.org/strings/properties> of the first
character. If no property is specified returns the
L<General Category|https://en.wikipedia.org/wiki/Unicode_character_property#General_Category>.
Returns a Bool for Boolean properties.

    say 'a'.uniprop;               # OUTPUT: «Ll␤»
    say '1'.uniprop;               # OUTPUT: «Nd␤»
    say 'a'.uniprop('Alphabetic'); # OUTPUT: «True␤»
    say '1'.uniprop('Alphabetic'); # OUTPUT: «False␤»

=head2 method uniprops

Defined as:

    sub uniprops(Str:D $str, Stringy:D $propname = "General_Category")

Interprets the invocant as a L<Str|/type/Str>, and returns the
L<unicode property|http://userguide.icu-project.org/strings/properties> for each character
as a Seq. If no property is specified returns the
L<General Category|https://en.wikipedia.org/wiki/Unicode_character_property#General_Category>.
Returns a Bool for Boolean properties. Similar to L<uniprop|/routine/uniprop>


=head2 method uniname

Defined as:

    sub uniname(Str(Cool) --> Str)
    method uniname(--> Str)

Interprets the invocant / first argument as a L<Str|/type/Str>, and returns the
Unicode codepoint name of the first codepoint of the first character. See
L<uninames|#routine_uninames> for a routine that works with multiple
codepoints, and L<uniparse> for the opposite direction.

    # Camelia in Unicode
    say ‘»ö«’.uniname;
    # OUTPUT: «"RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK"␤»
    say "Ḍ̇".uniname; # Note, doesn't show "COMBINING DOT ABOVE"
    # OUTPUT: «"LATIN CAPITAL LETTER D WITH DOT BELOW"␤»

    # Find the char with the longest Unicode name.
    say (0..0x1FFFF).sort(*.uniname.chars)[*-1].chr.uniname;
    # OUTPUT: ««ARABIC LIGATURE UIGHUR KIRGHIZ YEH WITH HAMZA ABOVE WITH ALEF MAKSURA INITIAL FORM␤»␤»

=head2 method uninames

Defined as:

    sub uninames(Str:D)
    method uninames()

Returns of a Seq of Unicode names for the all the codepoints in the Str provided.

    say ‘»ö«’.uninames.perl;
    # OUTPUT: «("RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK", "LATIN SMALL LETTER O WITH DIAERESIS", "LEFT-POINTING DOUBLE ANGLE QUOTATION MARK").Seq␤»

Note this example, which gets a Seq where each element is a Seq of all the
codepoints in that character.

    say "Ḍ̇'oh".comb>>.uninames.perl;
    # OUTPUT: «(("LATIN CAPITAL LETTER D WITH DOT BELOW", "COMBINING DOT ABOVE").Seq, ("APOSTROPHE",).Seq, ("LATIN SMALL LETTER O",).Seq, ("LATIN SMALL LETTER H",).Seq)␤»

See L<uniparse> for the opposite direction.

=head2 method unimatch

Defined as:

    multi sub unimatch(Str:D $str, |c)
    multi unimatch(Int:D $code, Stringy:D $pvalname, Stringy:D $propname = $pvalname)

Checks if the given integer codepoint or the first letter of the string given have a unicode property
equal to the value you give. If you supply the Unicode property to be checked it will only return True
if that property matches the given value.

    say unimatch 'A', 'Latin';           # OUTPUT: «True␤»
    say unimatch 'A', 'Latin', 'Script'; # OUTPUT: «True␤»
    say unimatch 'A', 'Ll';              # OUTPUT: «True␤»

=head2 routine chop

Defined as:

    sub chop(Str(Cool))
    method chop()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it with the last
character removed.

    say 'perl'.chop;                        # OUTPUT: «per␤»

=head2 routine chomp

Defined as:

    sub chomp(Str(Cool))
    method chomp()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it with the last
character removed, if it is a logical newline.

    say 'ab'.chomp.chars;                   # OUTPUT: «2␤»
    say "a\n".chomp.chars;                  # OUTPUT: «1␤»

=head2 routine substr

Defined as:

    sub substr(Str(Cool) $str, $from, $chars?)
    method substr($from, $chars?)

Coerces the invocant (or in the sub form, the first argument) to
L<Str|/type/Str>, and returns the string starting from offset C<$from>. If
C<$chars> is supplied, at most C<$chars> characters are returned.

    say 'zenith'.substr(2);         # OUTPUT: «nith␤»
    say 'zenith'.substr(0, 3);      # OUTPUT: «zen␤»

    # works on non-strings too:
    say 20151224.substr(6);         # OUTPUT: «24␤»

    # sub form:
    say substr "zenith", 0, 3;      # OUTPUT: «zen␤»

If the C<$from> parameter is a L<Callable|/type/Callable>, it is called with
the number of chars in the string as argument. This allows easy indexing
relative to the end:

    say 20151224.substr(*-2);       # OUTPUT: «24␤»

=head2 routine ords

Defined as:

    sub ords(Str(Cool) $str)
    method ords()

Coerces the invocant (or in the sub form, the first argument) to
L<Str|/type/Str>, and returns a list of Unicode codepoints for each character.

    say "Camelia".ords;              # OUTPUT: «67 97 109 101 108 105 97␤»
    say ords 10;                     # OUTPUT: «49 48␤»

This is the list-returning version of L<ord>. The inverse operation in
L<chrs>. If you are only interested in the number of codepoints,
L<codes> is a possibly faster option.

=head2 routine chrs

Defined as:

    sub chrs(*@codepoints --> Str:D)
    method chrs()

Coerces the invocant (or in the sub form, the argument list) to a list of
integers, and returns the string created by interpreting each integer as a
Unicode codepoint, and joining the characters.

    say <67 97 109 101 108 105 97>.chrs;   # OUTPUT: «Camelia␤»

This is the list-input version of L<chr>. The inverse operation is L<ords>.

=head2 routine split

Defined as:

    multi sub    split(  Str:D $delimiter, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
    multi sub    split(Regex:D $delimiter, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
    multi sub    split(@delimiters, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
    multi method split(  Str:D $delimiter, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
    multi method split(Regex:D $delimiter, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
    multi method split(@delimiters, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)

Coerces the invocant (or in the sub form, the second argument) to
L<Str|/type/Str>, and splits it into pieces based on delimiters found in the
string.

If C<$delimiter> is a string, it is searched for literally and not treated
as a regex. You can also provide multiple delimiters by specifying them as a
list; mixing Cool and Regex objects is OK.

    say split(';', "a;b;c").perl;               # OUTPUT: «("a", "b", "c")␤»
    say split(';', "a;b;c", 2).perl;            # OUTPUT: «("a", "b;c").Seq␤»

    say split(';', "a;b;c,d").perl;             # OUTPUT: «("a", "b", "c,d")␤»
    say split(/\;/, "a;b;c,d").perl;            # OUTPUT: «("a", "b", "c,d")␤»
    say split(/<[;,]>/, "a;b;c,d").perl;        # OUTPUT: «("a", "b", "c", "d")␤»

    say split(['a', /b+/, 4], '1a2bb345').perl; # OUTPUT: «("1", "2", "3", "5")␤»

By default, split omits the matches, and returns a list of only those parts of
the string that did not match. Specifying one of the C<:k, :v, :kv, :p> adverbs
changes that. Think of the matches as a list that is interleaved with the
non-matching parts.

The C<:v> interleaves the values of that list, which will be either
L<Match|/type/Match> objects, if a L<Regex|/type/Regex> was used as a matcher
in the split, or L<Str|/type/Str> objects, if a L<Cool|/type/Cool> was used
as matcher. If multiple delimiters are specified, L<Match|/type/Match> objects
will be generated for all of them, unless B<all> of the delimiters are
L<Cool|/type/Cool>.

    say 'abc'.split(/b/, :v);               # OUTPUT: «(a ｢b｣ c)␤»
    say 'abc'.split('b', :v);               # OUTPUT: «(a b c)␤»

C<:k> interleaves the keys, that is, the indexes:

    say 'abc'.split(/b/, :k);               # OUTPUT: «(a 0 c)␤»

C<:kv> adds both indexes and matches:

    say 'abc'.split(/b/, :kv);               # OUTPUT: «(a 0 ｢b｣ c)␤»

and C<:p> adds them as L<Pairs|/type/Pair>, using the same types for
values as C<:v> does:

    say 'abc'.split(/b/, :p);               # OUTPUT: «(a 0 => ｢b｣ c)␤»
    say 'abc'.split('b', :p);               # OUTPUT: «(a 0 => b c)␤»

You can only use one of the C<:k, :v, :kv, :p> adverbs in a single call
to C<split>.

Note that empty chunks are not removed from the result list.
For that behavior, use the `:skip-empty` named argument:

    say ("f,,b,c,d".split: /","/             ).perl;  # OUTPUT: «("f", "", "b", "c", "d")␤»
    say ("f,,b,c,d".split: /","/, :skip-empty).perl;  # OUTPUT: «("f", "b", "c", "d")␤»

See also: L<comb>.

=head2 routine lines

Defined as:

    sub lines(Str(Cool))
    method lines()

Coerces the invocant (and in sub form, the argument) to L<Str|/type/Str>,
decomposes it into lines (with the newline characters stripped), and returns
the list of lines.

    say lines("a\nb\n").join('|');          # OUTPUT: «a|b␤»
    say "some\nmore\nlines".lines.elems;    # OUTPUT: «3␤»


This method can be used as part of an C<IO::Path> to process a file
line-by-line, since C<IO::Path> objects inherit from C<Cool>, e.g.:

=begin code
for 'huge-csv'.IO.lines -> $line {
    # Do something with $line
}

# or if you'll be processing later
my @lines = 'huge-csv'.IO.lines;
=end code

Without any arguments, sub C<lines> operates on
C<$*ARGFILES>, which defaults to C<$*IN> in the absence of any filenames.

To modify values in place use C<is copy> to force a writable container.

=for code
for $*IN.lines -> $_ is copy { s/(\w+)/{$0 ~ $0}/; .say }

=head2 method words

Defined as:

    method words(Int() $limit)

Coerces the invocant to L<Str|/type/Str>, and returns a list of words that make
up the string (and if C<$limit> is supplied, only the first C<$limit> words).

    say 'The quick brown fox'.words.join('|');      # OUTPUT: «The|quick|brown|fox␤»
    say 'The quick brown fox'.words(2).join('|');   # OUTPUT: «The|quick␤»

Only whitespace counts as word boundaries

    say "isn't, can't".words.join('|');             # OUTPUT: «isn't,|can't␤»

=head2 routine comb

Defined as:

    multi sub comb(Regex $matcher, Str(Cool) $input, $limit = * --> Seq)
    multi method comb(Regex $matcher, $limit = * --> Seq)

Returns all (or if supplied, at most C<$limit>) matches of the invocant
(method form) or the second argument (sub form) against the
L<Regex|/type/Regex> as a list of strings.

    say "6 or 12".comb(/\d+/).join(", ");           # OUTPUT: «6, 12␤»

=head2 method contains

    multi method contains(Cool:D: Str(Cool) $needle, Cool $start? --> Bool:D)

Coerces the invocant and first argument to L<Str|/type/Str>, and searches for
C<$needle> in the string starting from C<$start>. Returns C<True> if C<$needle>
is found.

    say "Hello, World".contains('Hello');      # OUTPUT: «True␤»
    say "Hello, World".contains('hello');      # OUTPUT: «False␤»
    say "Hello, World".contains(',');          # OUTPUT: «True␤»
    say "Hello, World".contains(',', 3);       # OUTPUT: «True␤»
    say "Hello, World".contains(',', 10);      # OUTPUT: «False␤»

Note that because of how a L<List|/type/List> or L<Array|/type/Array> is
L<coerced|/type/List#method_Str> into a L<Str|/type/Str>, the results may
sometimes be surprising. See L<traps|/language/traps#Lists_become_strings,_so_beware_.contains>.

=head2 routine index

Defined as:

    multi sub    index(Str(Cool) $s, Str:D $needle, Int(Cool) $startpos = 0 --> Int)
    multi method index(Str(Cool) $needle, Int(Cool) $startpos = 0 --> Int)

Coerces the first two arguments (in method form, also counting the invocant)
to L<Str|/type/Str>, and searches for C<$needle> in the string starting from C<$startpos>.
It returns the offset into the string where C<$needle> was found, and an undefined
value if it was not found.

See L<the documentation in type Str|/type/Str#routine_index> for examples.

=head2 routine rindex

Defined as:

    multi sub    rindex(Str(Cool) $haystack, Str(Cool) $needle, Int(Cool) $startpos = $haystack.chars)
    multi method rindex(Str(Cool) $haystack: Str(Cool) $needle, Int(Cool) $startpos = $haystack.chars)

Coerces the first two arguments (including the invocant in method form) to
L<Str|/type/Str> and C<$startpos> to L<Int|/type/Int>, and
returns the last position of C<$needle> in C<$haystack> not after C<$startpos>.
Returns an undefined value if C<$needle> wasn't found.

See L<the documentation in type Str|/type/Str#routine_rindex> for examples.

=head2 routine match

Defined as:

    multi method match(Cool:D: $target, *%adverbs)

Coerces the invocant to L<Str|/type/Str> and calls the method L<match|/type/Str#method_match> on it.

=head2 method fmt

Defined as:

    method fmt($format = '%s' --> Str:D)

Uses C<$format> to return a formatted representation of the invocant.

For more information about formats strings, see L<sprintf|/routine/sprintf>.

    say 11.fmt('This Int equals %03d');               # OUTPUT: «This Int equals 011␤»
    say '16'.fmt('Hexadecimal %x');                   # OUTPUT: «Hexadecimal 10␤»

=head2 routine roots

Defined as:

    multi sub roots(Numeric(Cool) $x, Int(Cool) $n)
    multi method roots(Int(Cool) $n)

Coerces the first argument (and in method form, the invocant) to
L<Numeric|/type/Numeric> and the second (C<$n>) to L<Int|/type/Int>, and produces a
list of C<$n> L<Complex|/type/Complex> C<$n>-roots, which means numbers that,
raised to the C<$n>th power, approximately produce the original number.

For example

=begin code
my $original = 16;
my @roots = $original.roots(4);
say @roots;

for @roots -> $r {
    say abs($r ** 4 - $original);
}

# OUTPUT:«2+0i 1.22464679914735e-16+2i -2+2.44929359829471e-16i -3.67394039744206e-16-2i␤»
# OUTPUT:«1.77635683940025e-15␤»
# OUTPUT:«4.30267170434156e-15␤»
# OUTPUT:«8.03651692704705e-15␤»
# OUTPUT:«1.04441561648202e-14␤»
=end code

=head2 method IO

Defined as:

    method IO(--> IO::Path:D)

Coerces the invocant to L<IO::Path>.

=for code
.say for '.'.IO.dir;        # gives a directory listing

=head2 routine EVAL

Defined as:

=for code
    method EVAL(*%_)
=for code
    sub EVAL($code where Cool|Blob, :$lang = 'perl6')

Method form calls subroutine form with invocant as C<$code>, passing along
named args, if any. Subroutine form coerces L<Cool> C<$code> to L<Str>.
If C<$code> is a L<Blob>, it'll be processed using the same encoding as
the C<$lang> compiler would: for C<perl6>, uses the encoding specified
via C<--encoding> command line argument, or C<utf-8> if none were given;
for C<Perl5>, processes using same rules as C<perl>.

This works as-is with a literal string parameter. More complex input, such as
a variable or string with embedded code, is illegal by default. This can be
overridden in any of several ways:

    use MONKEY-SEE-NO-EVAL;
    use MONKEY;  # shortcut that turns on all MONKEY pragmas
    use Test;

    # any of the above allows:
    EVAL "say { 5 + 5 }";   # OUTPUT: «10␤»

Symbols in the current lexical scope are visible to code in an C<EVAL>.

    my $answer = 42;
    EVAL 'say $answer;';    # OUTPUT: «42␤»

However, since the set of symbols in a lexical scope is immutable after compile
time, an EVAL can never introduce symbols into the surrounding scope.

=for code :skip-test
EVAL 'my $lives = 9'; say $lives;   # error, $lives not declared

Furthermore, the C<EVAL> is evaluated in the current package:

    module M {
        EVAL 'our $answer = 42'
    }
    say $M::answer;         # OUTPUT: «42␤»

And also the current language, meaning any added syntax is available:

    sub infix:<mean>(*@a) is assoc<list> {
        @a.sum / @a.elems
    }
    EVAL 'say 2 mean 6 mean 4';     # OUTPUT: «4␤»

An C<EVAL> statement evaluates to the result of the last statement:

    sub infix:<mean>(*@a) is assoc<list> {
        @a.sum / @a.elems
    }
    say EVAL 'say 1; 2 mean 6 mean 4';         # OUTPUT: «1␤4␤»

C<EVAL> is also a gateway for executing code in other languages:

=for code
EVAL "use v5.20; say 'Hello from perl5!'", :lang<Perl5>;

=head2 routine EVALFILE

Defined as:

    sub EVALFILE($filename where Blob|Cool, :$lang = 'perl6')

Slurps the specified file and evaluates it. Behaves the same way as C<EVAL>
with regard to L<Blob> decoding, scoping, and the C<$lang> parameter. Evaluates to the value
produced by the final statement in the file.

=for code
EVALFILE "foo.p6";

=begin comment

TODO:
unpolar, fmt, substr-rw, trans,
match, subst, sprintf, printf, samecase

=end comment

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
